Interactions Between Caps, Joins, Dashes, and Patterns (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / About Geometric Styles

Interactions Between Caps, Joins, Dashes, and Patterns
The cap, join, dash, and pattern properties of the style object allow you to change the way QuickDraw GX draws the contours of a shape. The cap and join properties allow you to place arbitrary shapes on the geometric points of a shape's contours. For example, you can place arrow heads at the ends of a line, or you can put rounded edges at the corners of a rectangle. The dash property allows you to dash the contours of one shape with another shape. For example, you could dash a line with a circular path shape to get a dotted line.
The pattern property allows you to fill a shape (or the frame of a shape drawn with a thick pen width) with a repeated pattern of another shape. For example, you could fill a large square shape with a pattern of small squares to get a checkerboard.
Figure 3-14 shows some of the stylistic variations possible with caps, joins, dashes, and patterms.
Figure 3-14 Caps, joins, dashes, and patterns

There is one important rule that applies to all four of these properties: Cap shapes, join shapes, dash shapes, and pattern shapes must all be in their primitive form. When QuickDraw GX uses a cap, join, dash, or pattern shape, it ignores the stylistic variations of that shape. If you want a cap, join, dash, or pattern shape to have stylistic variations itself, you must first incorporate those stylistic variations into the shape using the GXPrimitiveShape function.
As an example, specifying a line shape with a thick pen (like the one in Figure 3-3 on page 3-9) as a cap, join, dash, or pattern shape may produce an unexpected result or post an error, since the shape is not in its primitive form. However, if you use the GXPrimitiveShape function, you can convert the line to a filled polygon, which is a perfectly acceptable cap, join, dash, or pattern shape.
The sections "The Cap Structure" on page 3-99, "The Join Structure" on page 3-101, "The Dash Structure" on page 3-103, and"The Pattern Structure" on page 3-106 discuss the types of shapes appropriate to use as caps, joins, dashes, and patterns.
As another example, a polygon with zero contours is not an acceptable cap, join, dash, or pattern shape, as it is not in its primitive form. Similarly, any shape with the no-fill shape fill is not in its primitive form. However, the empty shape, which is in its primitive form, is an acceptable cap, join, dash, or pattern shape. You can find more information about polygon shapes, polygon contours, and empty shapes in Chapter 2, "Geometric Shapes," in this book.
You can always be sure your cap, join, dash, or pattern shape is in the correct form by calling the GXPrimitiveShape function, which is described in Chapter 4, "Geometric Operations," before setting the corresponding style property.
As for typographic shapes, text and layout shapes are not in their primitive form, but glyph shapes are acceptable as cap, join, dash, and pattern shapes so long as they have no text face or tags and do not have caps, joins, dashes, or patterns themselves.
For more information, see Inside Macintosh: QuickDraw GX Typography.
You can use bitmap shapes as patterns, but not as caps, joins, or dashes, and you cannot use picture shapes for caps, joins, dashes, or patterns.
The next few sections describe caps, joins, dashes, and patterns in more detail.

Caps
QuickDraw GX allows you to specify cap shapes--what to draw at the start and at the end of a shape's contours. In particular, you can specify a start cap for any point shape, and you can specify a start cap and an end cap for any line, curve, polygon, or path shape that has open-frame shape fill.
In fact, the only way to draw a point shape is to specify a start cap for it (unless its style object has a pen width property with a value of 0, in which case QuickDraw GX draws the point shape as a single pixel).
QuickDraw GX uses the cap property of a shape's style object to store information about the start cap and end cap of the shape.
Figure 3-15 shows how QuickDraw GX adds a cap to a contour by centering the cap shape at the end of the contour, scaling the cap shape by the pen width, and rotating the cap shape to match the slope of the contour.
Figure 3-15 A shape with caps

The cap property of a style object includes a cap attributes field, which allows you to specify level caps--caps that QuickDraw GX does not rotate to match the slope of the contour--as shown in Figure 3-16.
Figure 3-16 A shape with level caps

You can create two standard cap types by specifying half a square or a semicircle for the start cap or end cap shape, as shown in Figure 3-17.
Figure 3-17 Standard cap shapes

The sections "Adding Caps to a Shape" on page 3-57 and "Adding Standard Caps to a Shape" on page 3-59 give examples of using the cap property, the sections "The Cap Structure" on page 3-99 and "Cap Attributes" on page 3-101 describe the data structures used to store information about caps, and the section "Getting and Setting Caps" beginning on page 3-123 describes the functions you can use to manipulate caps.

Joins
QuickDraw GX allows you to specify a join shape to be drawn at the corners of another shape's contours. In particular, you can specify a join shape for any rectangle, polygon, or path shape that has an open-frame shape fill or a closed-frame shape fill:

For shapes with the closed-frame shape fill, QuickDraw GX draws the specified join shape at every on-curve geometric point of each contour.
For shapes with the open-frame shape fill, QuickDraw GX draws the specified join shape at every on-curve geometric point between the first point and the last point of each contour.

QuickDraw GX uses the join property of a shape's style object to store information about the joins of a shape.
Figure 3-18 shows how QuickDraw GX adds a join to a contour by centering the join shape on the on-curve geometric points, scaling the join shape by the pen width, and rotating the join shape to match the mid-angle of the two line segments that make up the corner.
Figure 3-18 A shape with joins

The join property of a style object includes a join attributes field, which allows you to specify level joins--joins that QuickDraw GX does not rotate to match the slope of the contour--as shown in Figure 3-19.
Figure 3-19 A shape with level joins

You can also use the join attributes to specify two types of standard joins--sharp joins and curve joins, as shown in Figure 3-20.
Figure 3-20 Standard joins

For sharp joins, QuickDraw GX allows you to specify a miter--the maximum distance between the actual corner of a shape's geometry and the corner as drawn, as shown in Figure 3-21.
Figure 3-21 Sharp join with miter

The sections "Adding Joins to a Shape" on page 3-61 and "Adding Standard Joins to a Shape" on page 3-64 give examples of using the join property, the section "The Join Structure" on page 3-101 and "Join Attributes" on page 3-102 describe the data structures used to store information about joins, and the section "Getting and Setting Joins" on page 3-129 describes the functions you can use to manipulate them.

Dashes
With QuickDraw GX, you can specify that framed shapes should be drawn with dashed, instead of solid, contours. In particular, you may specify a dash shape for any line, curve, rectangle, polygon, or path shape that has an open-frame shape fill or a closed-frame shape fill.
QuickDraw GX uses the dash property of a shape's style object to store information about how to dash the shape.
Figure 3-22 shows how QuickDraw GX dashes a contour by placing copies of the dash shape along the contour at regular intervals, and rotating the dash shape to match the slope of the contour.
Figure 3-22 A dashed shape

When drawing a dashed shape, QuickDraw GX automatically scales the dash shape up by the pen width of the dashed shape. However, unlike cap and joins, QuickDraw GX scales dashes only perpendicularly to the dashed contour.
For example, if the height of the dash shape is 1.0, then QuickDraw GX draws the dashes with a height equal to the dashed shape's pen width. If the height of the dash shape is 2.0, then QuickDraw GX draws the dashes with a height equal to twice the dashed shape's pen width.
Since the dash shape is scaled up by the pen width of the dashed shape, QuickDraw GX provides a way for you to scale the dash down, as well, by providing a scaling factor, called the dash scale, in one of the fields of the dash structure. QuickDraw GX multiplies the height of the dash by the pen width and then divides by the dash scale.
Figure 3-23 shows the effect of different pen widths on the same dash shape. In this example, the dash shape has height of 10.0 (its y-coordinates span from -5.0 to 5.0). The shape being dashed is a curve. The curve is shown first with a pen width of 10.0 and a dash scale of 10.0, which keeps the dimensions of the dash shape unchanged. The curve is then shown with a pen width of 20.0 and a dash scale of 10.0, which doubles the size of the dash shape in the y-coordinate direction.
Figure 3-23 Scaling a dash shape

Note
Glyph shapes are an exception to this scaling rule. If the dash shape is a glyph shape, QuickDraw GX does not scale the dashes (which in this case would be glyphs) to the dashed shape's pen width.
Notice that the position of a dash shape in the coordinates of its geometry space is significant. For example, if the y-coordinates of the geometry of a dash shape span from 1.0 to 2.0, then QuickDraw GX draws the dashes at a distance of one pen width to the outside of the dashed contour (if the dash scale is 1.0). If the lowest y-coordinate of a dash shape is 2.0, then QuickDraw GX draws the dashes at a distance of two pen widths to the outside of the contour (if the dash scale is 1.0).
If the y-coordinates of the geometry of a dash shape are large enough and the scaling factor you provided in the dash structure is small enough, the dashes may exceed the pen width of the dashed shape. QuickDraw GX provides the clip dash attribute to indicate that QuickDraw GX should clip the dashes to the pen width, as illustrated in Figure 3-24.
Figure 3-24 Effect of the clip dash attribute

Setting the clip dash attribute causes some intricate interactions among dashes, caps, joins, and patterms. See "Interactions Between Caps, Joins, Dashes, and Patterns" on page 3-33 for more information.
QuickDraw GX also allows you to control how far apart the dashes appear from one another, which is called the dash advance, and how far into the dash shape the dashing should start, which is called the dash phase.
The dash advance is the distance between the start of one dash shape and the start of the next dash shape along the contour. The dash phase indicates where the first dash should fall on a contour; it is a percentage of the dash advance.
When a dash shape has multiple contours, it is possible for the dashes not to fall on the contours of the dashed shape. For this situation, QuickDraw GX provides the break dash attribute, which indicates that each contour of the dash should be rotated and placed separately on the dashed shape's contours. Figure 3-25 depicts the result of setting this dash attribute.
Figure 3-25 Effects of breaking a dash

Finally, QuickDraw GX provides a dashing feature that works only when dashing hairline contours. In this case, you can set the bend dash attribute, which indicates that QuickDraw GX should wrap the dash to fit the dashed contour exactly, as shown in Figure 3-26.
Figure 3-26 Effects of bending a dash

The following sections give examples of dashing:

"Dashing a Shape" on page 3-66
"Adjusting Dashes to Fit Contours" on page 3-70
"Insetting Dashes" on page 3-73
"Breaking and Bending Dashes" on page 3-74
"Wrapping Text to a Contour" on page 3-80
"Determining Dash Positions" on page 3-81

The section "The Dash Structure" on page 3-103 and"Dash Attributes" on page 3-105 describe the data structures used to store and communicate information about dashes, and the section "Getting and Setting Dashes" on page 3-134 describes the functions you can use to manipulate the dash property.

Patterns
With QuickDraw GX, you can specify that certain shapes be filled with a pattern. For shapes with solid shape fills, QuickDraw GX fills the shape by repeating a pattern shape that you specify.
You can also pattern framed shapes. For example, if you pattern a rectangle shape with a closed-frame shape fill and a pen width of 20.0, QuickDraw GX would fill the frame of the rectangle with the pattern. See the section "Interactions Between Caps, Joins, Dashes, and Patterns" on page 3-33 for more intricate examples.
QuickDraw GX uses the pattern property of a shape's style object to store information about how to pattern the shape.
Figure 3-27 shows how QuickDraw GX patterns a shape by filling the shape with copies of another shape, called the pattern shape, placed according to a regular grid that you specify.
Figure 3-27 A shape with a pattern

In addition to specifying the shape to use as the pattern shape, you also specify the pattern grid on which to place the pattern, as shown in Figure 3-28.
Figure 3-28 Pattern placed on a nonrectilinear grid

In addition, QuickDraw GX provides you with two pattern attributes: the port-align pattern attribute and the port-map pattern attribute. Setting the port-align pattern attribute allows you to specify that QuickDraw GX should align the pattern with the view device instead of with the geometry of the patterned shape. Figure 3-29 shows the effect of setting this attribute.
Figure 3-29 Effects of the port-align pattern attribute

The port-map pattern attribute indicates that the pattern shape should not be affected by transformations to the patterned shape. For example, if you set this pattern attribute, scaling the patterned shape by a factor of two does not also scale the pattern shape by a factor of two; instead, more of the pattern is shown. Figure 3-30 shows the effect of setting this attribute.
Figure 3-30 Effects of the port-map pattern attribute

The sections "Adding a Pattern to a Shape" on page 3-86 and "Determining Pattern Positions" on page 3-88 give examples of using patterns. The section "The Pattern Structure" on page 3-106 and "Pattern Attributes" on page 3-107 describes the data structures used to store information about patterns, and the section "Getting and Setting Patterns" on page 3-142 describes the functions you can use to manipulate patterns.

Interactions Between Caps, Joins, Dashes, and Patterns
The previous four sections show the results of adding a cap, a join, a dash, or a pattern to a QuickDraw GX shape. This section discusses how these stylistic variations interact when you add more than one of them at a time to the same shape.
In general, these elements interact differently in each of these three cases:

the shape does not have a dash but has one or more of the other three stylistic variations
the shape does have a dash but the clip dash attribute is not set
the shape does have a dash and the clip dash attribute is set

When a shape has a cap and a join, QuickDraw GX adds the caps to the beginnings and ends of the shape's contours, and adds the joins to the other on-curve geometric points of the shape's contours. If the shape also has a pattern, QuickDraw GX draws this pattern throughout the shape's frame as well as the shape's caps and joins, as shown in Figure 3-31.
Figure 3-31 A shape with a cap, join, and pattern

If a shape has a dash, but the clip dash attribute is not set, QuickDraw GX ignores the caps and joins of the shape. However, if the shape has a pattern, QuickDraw GX does draw the pattern throughout the dashes, as shown in Figure 3-32.
Figure 3-32 A shape with a dash and a pattern

Finally, if the shape has a dash and the clip dash attribute is set, QuickDraw GX does not ignore the caps and joins. Instead, the cap shapes and the join shapes are added to the clip shape that QuickDraw GX uses to clip the dashes. Patterns are not allowed in this case. Figure 3-33 shows the interaction of a cap, join, and clipped dash.
Figure 3-33 A shape with a clipped dash and a cap and join

The section "Combining Caps, Joins, Dashes, and Patterns" beginning on page 3-91 give examples of the interactions between caps, joins, dashes, and patterns.